Using an Import Definition File

Use an import definition file to customize how .csv file data is imported into your system. The process requires two files: the source data file (.csv) and the import definition file (.idf), which is referenced via the import command parameters.

The .idf file is an XML file that is used to define custom conditions for a .csv file import. Use an .idf file during the import process to set the data source to show whether the imported file contains raw data or not, to specify what columns are required for the import, to define or override units for specific items, or to customize column header names by mapping each default column header name (FMS enumeration value) to a new column header name (user-provided value).

For history import files, a file collection time can also optionally be defined using the .idf file, and data aggregation must be defined using the .idf file for certain conditions.

• You must use an import definition file if you have opted not to specify a unit set in the command parameters.
• You must use an import definition file if you have columns in your history import .csv file for which both of the following are true.

• Your imported records will be rolled down
• Your history import file contains columns for the following data items.

• For gas periodic history import files, columns for custom device data items (eFMS_PV_PQ_CUSTOM 1-5 or eFMS_PV_PM_CUSTOM 1-5) or %Air (eFMS_PV_AIR).
• For ticket history import files, columns for custom device data items (eFMS_TICKET_CUSTOM*_STRING or eFMS_TICKET_CUSTOM*_FLOAT).

See the following configuration topics for more information about preparing and importing .csv files that may utilize an .idf file.

• Configuring File Import Commands: Configuration CSV
• Configuring File Import Commands: Gas Analysis CSV
• Configuring File Import Commands: Gas Quality CSV
• Configuring File Import Commands: History CSV

Setting Up Import File Folders

If you will be performing more than one type of file import, a simple way to set up your import folders is to make parallel folders in your chosen directory location. Create a separate folder for each CSV file type you will be importing, and clearly name each folder to reflect the appropriate type of data (shown as Configuration, Gas_Analysis, History_Gas_Periodic, History_Ticket, and Send_Configuration in the example below). Each folder would then contain its own "Failed" sub-directory, "Processed" sub-directory, and a properly configured data-type-specific IDF file.

Example

Renaming a History Import Definition File (IDF)

CygNet Measurement provides two separate samples of history IDF files, one to be used for gas periodic history data (CxFmsImportCsvHistoryGasPeriodic.idf) and one to be used for ticket history data (CxFmsImportCsvHistoryTicket.idf). In order for the service to find the file however, it must be titled CxFmsImportCsvHistory.idf, therefore the words "GasPeriodic" or "Ticket" must ultimately be deleted from your working IDF file name(s).

Creating the Import Definition File (IDF)

CygNet provides sample files you can adjust and use to create IDFs for new imports. Sample .idf files are located in the CygNet\Services\FMS\ImportSamples folder on your host server.

General Import Definition File Requirements

The following general requirements apply to Import Definition Files.

• The IDF must be specifically named for the import file type, so that the service can find it by the expected name:

• The Configuration IDF must be named CxFmsImportCsvConfig.idf.
• The Gas Analysis IDF must be named CxFmsImportCsvGasAnalysis.idf.
• The Gas Quality IDF must be named CxFmsImportCsvGasQuality.idf.
• The History IDF must be named CxFmsImportCsvHistory.idf.

  Note: Sample .idf files are provided for both gas periodic (CxFmsImportCsvHistoryGasPeriodic.idf) and ticket (CxFmsImportCsvHistoryTicket.idf) data, but for either type you must rename the file to CxFmsImportCsvHistory.idf before it is used.

• The .csv file can be imported as a Device file or a User file, using the setting defined in the .idf file. Set the value of textFilesTrusted equal to "true" to import the .csv as a Device file (raw data). Set the value equal to "false" to import the .csv as a User file (not raw data).
• A new ColumnMapping name can be mapped to the default column name (the FMS enumeration string). Once the column is mapped, it will only be expected under the new name; the FMS enumeration name will no longer be recognized.
• Non-required columns that have a value in the source file, but are not listed in the .idf file, will use the default enum column name. If a non-required column does not exist in the source file, the column will be skipped.
• Required columns, those for which required="true" in the .idf file, must have a value in the source file. If a column required for the import does not exist in the source file, the import will fail.

Import Definition File Structure

The structure of an .idf file for importing configuration data is shown in the following example.

The structure of an .idf file for importing gas periodic history data, using the fileCollectionTime property, is shown in the following example.

The structure of an .idf file for importing ticket history data, using the fileCollectionTime property, is shown in the following example.

Import Definition File Elements

The following .idf file elements can be used to custom define options in your configuration file import.

The FileImportDefinition element is the root element of the XML file. The properties of this element are as follows.

• textFilesTrusted —defines whether or not the text files you are importing are trusted as a raw data source. Possible values are ="true" (file trusted) or ="false" (file not trusted).
• fileCollectionTime — for history .csv imports (not applicable to configuration .csv imports), can optionally be used to define the collection date/time of the data file. If left blank, the value will default to the date/time of the file import.

The ColumnMapping element defines each column header. The properties of this element are as follows.

• name — the name of the column header as you want it to appear. The ColumnMapping name element is user defined.
• enum — the FMS enumeration name, which appears as the column header name by default if not mapped otherwise. The enum elements are defined in FMS.

  See FMS Configuration Items, FMS History Items and FMS Ticket Items for more information about EFM data items.

• required — defines whether or not the column is required to have a value in the source data file in order to perform the import. Possible values are ="true" (required) or ="false" (not required). The required element is user defined.
• units - defines the units to be used for the enumerated item. This property can be used for either of the following purposes.
  • To override the units to use for specific items, even though a unit set has been specified as a command parameter
  • To provide the units to use for each item requiring units, when no unit set has been specified as a command parameter

• aggregation — defines how the import data was aggregated, so that imported records can be rolled down. This element is required when both of the following circumstances are true.
  • Your imported records will be rolled down
  • Your import file contains columns for custom device data items (eFMS_PV_PQ_CUSTOM 1-5, or eFMS_PV_PM_CUSTOM 1-5) or %Air (eFMS_PV_AIR)

  Possible values are ="Average" or ="Sum". Acceptable values are case insensitive. Invalid values for this element will cause the import to fail.

  See Configuring Custom Device Data for more information about mapping custom device data items.

• ValueMapping — for certain columns (e.g. HeatingValueBasis in Gas Analysis IDFs, or CalcMethodFPV in Configuration IDFs), defines which enumeration values to map to given inputs, without inserting the numerical representation of the value type option; a meaningful user-defined name can optionally be entered and used instead of the supplied default name.

  Example

  When mapping HeatingValueBasis values for a Gas Analysis IDF, the numbers 1, 2, and 3 represent the value type options of Wet, Dry, and As delivered, respectively. Without looking these values up, you can specify either Wet, Dry, or As delivered (the default name values), OR enter a user-defined term for each of these name values, and the correct heating value basis type will be inserted into the CSV file column.

  <ColumnMapping name= "HeatingValueBasis" enum= "eFMS_CFG_GAS_ANALYSIS_HEATING_VALUE_BASIS" required="false">

  <ValueMapping name= "Dry (or user-defined name)" enum= "eFMS_CFG_HEATING_VALUE_BASIS_DRY">

  <ValueMapping name= "Wet (or user-defined name)" enum= "eFMS_CFG_HEATING_VALUE_BASIS_WET">

  <ValueMapping name= "As delivered (or user-defined name)" enum= "eFMS_CFG_HEATING_VALUE_BASIS_AS_DELIVERED">

  </ColumnMapping>